home *** CD-ROM | disk | FTP | other *** search
/ Floppyshop 2 / Floppyshop - 2.zip / Floppyshop - 2.iso / art&graf.ix / art-5276 / picfb11a / doc / picfib_e.txt < prev    next >
Text File  |  1995-11-28  |  14KB  |  331 lines
  1. PICFIB Documentation V1.1a 1995.11.28 for PICFIB V1.1a from 1995.11.28
  2.  
  3.  
  4.                         P I C F I B
  5.  
  6.                             by
  7.  
  8.                       A. Rosenberg (AR)
  9.  
  10.  
  11. DISCLAIMER: Don't hold me (AR) responsible for any damage you may
  12. encounter while using this program. I tried to remove all bugs and
  13. several people did some beta testing to find the rest.
  14.  
  15. DISTRIBUTION: This program is SHAREWARE. You may test it over a
  16. period of 30 days. If you find it useful and like to use it regularly
  17. you must register. Otherwise you are using an illegal copy.
  18. It may (and should) be copied and distributed over BBS but no fees
  19. must apply and the package must stay complete. It may be compressed and/or
  20. encoded for transmission/storage purpose.
  21. Comercial PD/Shareware distributors may not take more than $3 as copy
  22. fee.
  23.  
  24. REGISTRATION: The basic concept of SHAREWARE is to test the software
  25. if it suits your needs. If it does and you like to use it further, you
  26. must pay or you are using an illegal copy. The period of 30 days should
  27. be enough to decide if you like it or not. If you register, you will
  28. receive a key that removes the 10 file limit and the about box on exit.
  29. For more info about REGISTRATION read the file REGIST_E.TXT.
  30.  
  31.  
  32. 1. Overview
  33.  
  34. 1.1. What is PICFIB?
  35.  
  36. PICFIB stands for "PICture FIle Browser" and is a small utility that
  37. supports you in viewing a bunch of pictures. I got the idea for it one day
  38. when I got the ATARI GEMINI CD-ROM. It contained directories with dozens of
  39. IMG files (about 450). I viewed some and as I wanted to continue the next
  40. day I couldn't remember which I had already viewed. It was also a big mess
  41. to select FILE|OPEN before scrolling through the file list and select the
  42. next picture. To solve the problem I decided to write this utility.
  43.  
  44. 1.2. What PICFIB does
  45.  
  46. PICFIB allows you to create a list of pictures files by scanning through a
  47. specified directory. Each list entry has 4 tags assigned to the picture.
  48. Tag 1 is managed by the utility and stores information if this file has been
  49. viewed already. The other 3 tags are available to the user. You may set a
  50. filter and only view tagged (i.e. your favourite) pictures. Of course you
  51. can save and load the lists you created. PICFIB supports the following
  52. kinds of pictures: 2,4,16,256 colors/grays. You can view any picture
  53. in any resolution, but you will only see the most important planes of the
  54. picture if your resolution has less colors than required to view the
  55. picture. To improve the presentation of color/grayscale pictures in
  56. monochrome resolutions you can enable dithering using the Floyd/Steinberg
  57. method.
  58.  
  59. 1.3 Hardware requirements
  60.  
  61. PICFIB should run on any ST-Compatible computer in any palette based
  62. resolution (sorry, no True-Color support).
  63.  
  64. 1.4 Limitation of PICFIB
  65.  
  66. If you view pictures with more colors than your resolution supports the
  67. picture will be converted to a reduced color version. It depends on the
  68. video hardware if the result looks good or not. For photo realistic
  69. pictures you should use 256 colors. In the ST low resolution such
  70. pictures will look rather bad. Try to use the ST high resolution in these
  71. cases, because dithering will give better results. You can only
  72. load pictures that are smaller than 4096x4096 pixels and the available
  73. memory in your computer.
  74.  
  75.  
  76. 1.5 Supported graphic formats
  77.  
  78. PICFIB supports the following formats:
  79.  
  80. Extension       Description
  81.  
  82. IMG             GEM IMG format (including XIMG)
  83. PC1,PC2,PC3     DEGAS uncompressed/compressed for all ST resolutions
  84. PCX             ZSofts PC-Paintbrush format
  85. GIF             CompuServe's Graphics Interchange Format
  86. TIFF        Tagged Image File Format
  87. JPEG        Joint Picture Experts Group file format
  88.  
  89. Some notes on the TIFF format:
  90. The TIFF format was defined by Aldus and Microsoft and has been 
  91. redefined at least once. It is very flexible and you can store 
  92. additional information besides the picture. This flexibility has lead 
  93. to the problem, that many TIFF files don't match the definition to 
  94. 100%, because some programmers didn't follow the definition. So it has 
  95. happened that a program couldn't read the TIFF files it has created.
  96. The TIFF library I used is very exact concerning this problem and 
  97. refuses to load pictures with additional info that does not conform to the 
  98. definition (picture data is not affected). This happened to me several 
  99. times during the test phase. If it happens that a TIFF file is 
  100. rejected by PICFIB you can only try to save this TIFF file with a 
  101. second program hoping this creates valid files.
  102. Many thanks to Sam Leffler who has written this TIFF library and
  103. Dieter Linde who ported it to the Atari platform. See file TIFFCPRT.TXT 
  104. for details.
  105.  
  106. Some notes on the JPEG format:
  107. This library was also not written by myself and I would like to thank
  108. all members of the Independent JPEG Group who published their lib and
  109. made life so much easier for people like me. 
  110. JPEG is rather complex format and it requires a lot of memory to 
  111. decompress it. As a rough estimation you need about 10 bytes for each
  112. pixel in addition to the file itself and the image that is produced.
  113. So you would run out of memory very soon, but the members of the 
  114. Independent JPEG Group added functions to allow swapping memory to disk
  115. and make a much wider range of pictures loadable. THIS FEATURE IS 
  116. ALMOST NOT TESTED! I don't know what will happen on floppy only 
  117. machines with little memory.
  118.  
  119.  
  120. 2. The Menus of PICFIB
  121.  
  122. 2.1 The File menu
  123.  
  124. 2.1.1 Create List..
  125.  
  126. Select this item to create a new picture file list. You will get the file
  127. selector where you should select the path where your pictures reside. The
  128. list will contain all files matching the entered extension. Depending on
  129. the option 'Scan through subdirs' only the selected directory or the
  130. whole directory tree will be searched.
  131. Tag 1 for all files will be checked and the Tool dialog will be opened.
  132.  
  133. 2.1.2 Load List..
  134.  
  135. Select this item to load a previously stored list. The default extension for
  136. list files is 'TXT' since they are plain text files. The contents of the 
  137. file will be broken into lines. The Tool dialog will be opened. Version 1.0a 
  138. performs a security check to prevent accidential loading of text files that
  139. contain no PICFIB lists.
  140. When loading lists created with PICFIB V1.0 you will get a message box 
  141. "PICFIB signature not found. Continue?". Answer "YES" to continue loading. 
  142. Save the file again and the PICFIB signature will be included.
  143.  
  144. 2.1.3 Save List..
  145.  
  146. Select this item to save the current list. The default extension for list
  147. files is 'TXT' since they are plain text files. The tags for each entry are
  148. also saved. 
  149.  
  150. 2.1.4 Export List..
  151.  
  152. This function allows you to create list files for use by other 
  153. programs. First I'll present the export dialog and second I'll give 
  154. you some examples how to use it.
  155. The export dialog contains a checkbox named "Include PICFIB header". 
  156. Check this box if you plan to use the new list with PICFIB again. If
  157. you do so, you must enter exactly for character as a line prefix and 
  158. leave the line suffix empty. Otherwise PICFIB will be in trouble when 
  159. reading this list. If later versions of PICFIB should offer more tags 
  160. you will have to enter an according number of characters.
  161. The next check box is named "Use filter options". Only if you check 
  162. it, the other two radio buttons are used. If you use the "normal 
  163. filter" you will get exactly those pictures that match the tags you 
  164. checked in the options dialog (see section 2.1.5). Using the negated 
  165. filter option creates a list containing all pictures that DON'T match 
  166. the tags you checked.
  167. You may write some text into the edit fields below that is placed 
  168. before/after each line of the saved list.
  169.  
  170. Examples:
  171.         (X) checked check box, (*) checked radio button
  172.         ( ) unchecked check box/radio button
  173.         
  174. 1.) How to create a new PICFIB list with all pictures that have tag 2 
  175. and tag 3 checked. All pictures of the new list should have tag 4 
  176. checked.
  177.     -check tag 2 and tag 3 in the options dialog and choose "AND 
  178.     tags"
  179.     -choose "Export List.." and set the following 
  180.      (X) Include PICFIB header
  181.      (X) Use filter option
  182.      (*) Normal filter ( ) Negated filter
  183.     -at last enter "   +" as line prefix (3 spaces, one plus char)
  184.     -press OK and select/enter a filename in the file dialog.
  185.     
  186. 2.) How to create a batch file to copy all pictures that have tag 2 or 
  187. tag 4 checked to C:\PICS.
  188.     -check tag 2 and tag 4 in the options dialog and choose "OR 
  189.     tags"
  190.     -choose "Export List.." and set the following 
  191.      ( ) Include PICFIB header
  192.      (X) Use filter option
  193.      (*) Normal filter ( ) Negated filter
  194.     -enter "copy " as line prefix and "C:\PICS" as line 
  195.     suffix
  196.     -press OK and select/enter a filename with extension "BAT" 
  197.     in the file dialog.
  198.     -Now you can start this batch in any shell and the files will 
  199.     be copied.
  200.     
  201. 3.) How to create a batch file that deletes all files from C:\PICS 
  202. that have neither tag 2 nor tag 4 checked. (List must be created for
  203. C:\PICS)
  204.     -check tag 2 and tag 4 in the options dialog and choose "OR 
  205.     tags"
  206.     -choose "Export List.." and set the following 
  207.      ( ) Include PICFIB header
  208.      (X) Use filter option
  209.      ( ) Normal filter (*) Negated filter
  210.     -enter "del " as line prefix
  211.     -press OK and select/enter a filename with extension "BAT" 
  212.     in the file dialog.
  213.     -Now you can start this batch in any shell and the files will 
  214.     be deleted.
  215.  
  216. If you are useng a UNIX compatible shell use UNIX specific commands 
  217. instead (i.e."cp" and "rm").
  218.     
  219. 2.1.5 Options..
  220.  
  221. A dialog containing several check boxes appears. The first 4 check
  222. boxes corresponds with the tag numbers for each file. If you check one or
  223. more boxes you will only see pictures that have the appropiate tags checked.
  224. You can modify the filter with the option 'Match all tags' vs.'Match 1 tag'.
  225. 'Match all tags' means that the picture must have the same tags checked 
  226. as are checked here. 'Match 1 tag' means that a picture must have at least 
  227. one tag in common with the filter to be displayed. If you like to see all 
  228. unseen pictures you only need to check tag 1 here. Below are two additional
  229. check boxes. 'Scan through subdirs' affects only the creation of new lists.
  230. Depending on this option only the selected directory or the whole directory
  231. tree will be searched. 'Dither pics if mono res' enables dithering in 
  232. monochrome resolutions. This takes time of course, so don't worry if the 
  233. busy bee remains on the screen, while the disc light is already off. If you
  234. have dithering disabled and are viewing color/grayscale pictures you will 
  235. only see the most important plane. Sometimes you can get a first impression
  236. of the picture, but usually it won't look very good.
  237.  
  238.  
  239. 2.2 The View menu
  240.  
  241. 2.2.1 First pic
  242.  
  243. Select this item to load the first picture from file and display it in
  244. a window. This item is only available if you have created or loaded a
  245. list. Note that the filter options you set within the options dialog
  246. apply. So if you have set a filter and no file matches the filter you
  247. will get a message saying that the end of list was reached.
  248.  
  249. 2.2.2 Next pic
  250.  
  251. Select this item to load the next picture from file and display it.
  252. Filter options apply.
  253.  
  254. 2.2.3 Prev pic
  255.  
  256. Select this item to load the previous picture from file and display it.
  257. Filter options apply.
  258.  
  259. 2.2.4 Jump to pic
  260.  
  261. Select this item to jump to a specific picture. Enter the number you'd
  262. like to start viewing from. Filter options apply.
  263.  
  264. 2.2.5 Single pic
  265.  
  266. Select this item to load a single picture file and display it. It will
  267. not affect the picture list or other currently viewed pictures.
  268.  
  269. 2.2.6 Tool dialog
  270.  
  271. Select this item to open an additional window that offers more
  272. comfort in viewing the list and allows you to check/uncheck the tags
  273. for each file. The window has two buttons you can use to view the next/
  274. previous file (the right button means the next file). Below you see
  275. four check boxes that reflect the current state of the tags for this
  276. file. You may check/uncheck them the way you like. Note that tag
  277. number 1 will be automatically unchecked if the file is viewed. For
  278. more info about filtering of tags refer to section 2.1.4. You can
  279. remove this window by selecting this item again. If the window is open
  280. the menu item is checked.
  281.  
  282.  
  283. 3. Keyboard usage
  284.  
  285. Some functions are available exclusively or also via the keyboard
  286.  
  287. -keys 1-4 toggle the state of corresponding tag for the current 
  288. picture
  289. -use UNDO to toggle between the standard palette and the palette of 
  290. the current picture. This is useful if you view a picture with many 
  291. similar colors and you can't see the mouse or the menubar any more.
  292.  
  293.  
  294. 4. Miscellaneous
  295.  
  296. PICFIB (the base program) was written with Turbo C 2.0 on a ATARI 260ST 
  297. upgraded to 4MB and a Falcon030 in a period of about 8 weeks. The C source 
  298. occupies about 150KB. It was tested with TOS 1.04, 2.06, TOS 4.04, MagiC! 
  299. and in all resolutions a Falcon supports except 65536 color modes.
  300.  
  301. Known Bugs: None found so far.
  302.  
  303. Look at the file HISTORY.TXT to get more info about bugs being fixed in the
  304. current version.
  305.  
  306.  
  307. 4.1 The future of PICFIB
  308.  
  309. If I get enough response I will definitely do further development on
  310. PICFIB like additional file formats (i.e BMP...) and a function
  311. to create a picture of thumbnails from a list of pictures. I'm also
  312. planning to make a version for Windows (currently in the works).
  313.  
  314. 4.2 Bugs and features
  315.  
  316. Proposals and error reports are always welcome. Error reports should
  317. include info about:
  318. - kind of computer ST/STE/TT/Falcon + hardware (Memory,CPU-Upgrades,
  319. enhanced graphic cards,...)
  320. - TOS version
  321. - TSR programs (TOSFIX,NVDI,GDOS,...)
  322. - Accessories
  323. - resolution used while the error occurred (colors, Pixels x*y)
  324. - Blitter activated?
  325. - Does the error occur repeatedly?
  326. - detailed info about the last user actions before the error occured
  327. - kind of error (redraw problem, bombs, ...)
  328.  
  329. You find my address and how to contact me in REGIST_E.TXT.
  330.  
  331.